Skip Headers

Oracle® Database Data Cartridge Developer's Guide, 10g Release 2 (10.2) Part Number B14289-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# 19 Extensibility Constants, Types, and Mappings

This chapter describes System Defined Constants and System Defined Types, which apply generically to all supported languages. It also describes mappings that are specific to the PL/SQL, C, and Java languages.

This chapter contains these topics:

- System Defined Constants

- System-Defined Types

- Mappings of Constants and Types

## System Defined Constants

All the constants referred to in this chapter are defined in the `ODCIConst` package installed as part of the `catodci.sql` script. There are equivalent definitions for use within C routines in `odci.h`. You should use these constants instead of hard coding their underlying values in your routines. To ensure that the database or packet state are not inadvertently corrupted, the following statement is always used with these methods to restrict reads and writes:

    pragma restrict_references(ODCIConst, WNDS, RNDS, WNPS, RNPS);

The options described in this section fall into two categories:

- Bit-field values that can be combined using the `OR` operator are: `ODCIIndexAlter` options (Table 19-1), `ODCIIndexInfo` flag bits (Table 19-4), `ODCIPredInfo` flag bits (Table 19-5), `ODICI FuncInfo` flag bits(Table 19-6), `ODCIQueryInfo` flag bits (Table 19-7), `ODCIStatsOptions` flag bits (Table 19-8), and `ODCIStatsOptions` option bits (Table 19-9).

- Distinct values, where only one option can be specified, are: `ODCIArgDesc` `ArgType` values (Table 19-2), `ODCIEnv` `CallProperty` values (Table 19-3), `ScnFlg` values (Table 19-10), and `ReturnStatus` values (Table 19-11)

Table 19-1 ODCIIndexAlter Options

Name | Description
--- | ---
    AlterIndexNone
| Default option
    AlterIndexRename
| Rename Partition option
    AlterIndexRebuild
| Rebuild Index option
    AlterIndexUpdBlockRefs
| IOT Update Block References Option

Table 19-2 ODCIArgDesc.ArgType Values

Name | Description
--- | ---
    ArgOther
| Argument is other expression
    ArgCol
| Argument is a column name
    ArgLit
| Argument is a literal value
    ArgAttr
| Argument is an ADT `attr` column
    ArgCursor
| Argument is a `CURSOR` expression
    ArgNull
| Argument is `NULL`

Table 19-3 ODCIEnv.CallProperty Values

Name | Description
--- | ---
    None
| Default option
    FirstCall
| First partition call
    Intermediate Call
| Intermediate partition call
    FinalCall
| Final call after last partition

Table 19-4 ODCIIndexInfo.Flags Bits

Name | Description
--- | ---
    Local
| Indicates a local domain index
    RangePartn
| For a local domain index, indicates that the base table is range-partitioned. Is set only in conjunction with the `Local` bit
    Parallel
| Indicates that a parallel degree was specified for the index creation or alter operation
    Unusable
| Indicates that `UNUSABLE` was specified during index creation and that the index being created will be marked unusable
    IndexOnIOT
| Indicates that the domain index is defined on an index-organized table
    TransTblspc
| Indicates that the domain index is created in a transportable tablespace session.
    FunctionIdx
| Indicates that the index is a function-based domain index

Table 19-5 ODCIIPredInfo.Flags Bits

Name | Description
--- | ---
    PredExactMatch
| Equality predicate
    PredPrefixMatch
| `LIKE` predicate
    PredIncludeStart
| Include start value in index range scan
    PredIncludeStop
| Include stop value in index range scan
    PredObjectFunc
| Left hand side of predicate is a standalone function
    PredObjectPkg
| Left hand side of predicate is a package function
    PredObjectType
| Left hand site of predicate is a type method
    PredObjectTable
| Predicate contains columns from more than one table

Table 19-6 ODCIFuncInfo.Flags Bits

Name | Description
--- | ---
    ObjectFunc
| Standalone function
    ObjectPkg
| Package function
    ObjectType
| Type method

Table 19-7 ODCIQueryInfo.Flags Bits

Name | Description
--- | ---
    QueryFirstRows
| Optimizer mode is `FIRST_ROWS`
    QueryAllRows
| Optimizer mode is `ALL_ROWS`

Table 19-8 ODCIStatsOptions.Flags Bits

Name | Description
--- | ---
    EstimateStats
| Estimate statistics option
    ComputeStats
| Compute exact statistics option
    Validate
| Validate index option

Table 19-9 ODCIStatsOptions.Options Bits

Name | Description
--- | ---
    PercentOption
| Compute statistics by sampling
    RowOption
| Compute statistics based on all rows

Table 19-10 ScnFlg Values; Function with Index Context

Name | Description
--- | ---
    RegularCall
| User defined operator regular call
    CleanupCall
| User defined operator cleanup call

Table 19-11 Return Status Values

Name | Description
--- | ---
    Success
| Indicates a successful operation.
    Error
| Indicates an error.

## System-Defined Types

A number of system-defined types are defined by Oracle and need to be created by running the `catodci.sql` catalog script. The C mappings for these object types are defined in `odci.h`. The `ODCIIndex` and `ODCIStats` routines described in Chapter 20 and Chapter 21 use these types as parameters.

Unless otherwise mentioned, the names parsed as type attributes are unquoted identifiers.

### ODCIArgDesc

Object type. Stores function or operator arguments.

Table 19-12 DCIArgDesc Function/Operator Argument Description - Attributes

Name | Datatype | Description
--- | --- | ---
    ArgType
    NUMBER
| Argument type
    TableName
    VARCHAR2(30)
| Name of table
    TableSchema
    VARCHAR2(30)
| Schema containing the table
    ColName
    VARCHAR2(4000)
| Name of column. This could be top level column name such as "A", or a nested column "A"."B" Note that the column name are quoted identifiers.
    TablePartitionLower
    VARCHAR2(30)
| Contains the name of the lowest table partition that is accessed in the query
    TablePartitionUpper
    VARCHAR2(30)
| Contains the name of the highest table partition that is accessed in the query
    Cardinality
    NUMBER
| Cardinality value for `CURSOR` expressions

### ODCIArgDescList

Contains a list of argument descriptors

Datatype

    VARRAY(32767) of ODCIArgDesc

### ODCIRidList

Stores list of rowids. The rowids are stored in their character format.

Datatype

`VARRAY(32767) OF VARCHAR2("M_URID_SZ")`

### ODCIColInfo

Stores column related information.

Datatype

Object type.

Table 19-13 ODCIColInfo Column Related Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
    TableSchema
    VARCHAR2(30)
| Schema containing table
    TableName
    VARCHAR2(30)
| Name of table
    ColName
    VARCHAR2(4000)
| Name of column. This could be top level column name such as "A", or a nested column "A"."B" Note that the column name are quoted identifiers.
    ColTypeName
    VARCHAR2(30)
| Datatype of column
    ColTypeSchema
    VARCHAR2(30)
| Schema containing datatype if user-defined datatype
    TablePartition
    VARCHAR2(30)
| For a local domain index, contains the name of the specific base table partition

### ODCIColInfoList

Stores information related to a list of columns.

Datatype

`VARRAY(32) OF ODCIColInfo`

### ODCICost

Object type. Stores cost information.

Table 19-14 ODCICost Cost Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
    CPUCost
    NUMBER
| CPU cost
    IOCost
    NUMBER
| I/O cost
    NetworkCost
    NUMBER
| Communication cost
    IndexCostInfo
    VARCHAR2(255)
| Optional user-supplied information about the domain index for display in the `PLAN` table (255 characters maximum)

### ODCIEnv

Object type. Contains general information about the environment in which the extensibility routines are executing.

Table 19-15 ODCIEnv Environment Variable Descriptor Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
`EnvFlags` | `NUMBER` | 1 = Debugging On
`CallProperty` | `NUMBER` | 0 = None 1 = First Call 2 = Intermediate Call 3 = Final Call
`DebugLevel` | `NUMBER` | Indicates the level of debugging

Usage Notes

`CallProperty` is used only for local domain indexes. For non-local domain indexes it is always set to `0`. For local domain indexes, `CallProperty` is set to indicate which is the current call in cases where multiple calls are made to the same routine.

For example, when creating a local domain index, the `ODCIIndexCreate` routine is called n+2 times, where n is the number of partitions. For the first call, `CallProperty` is set to `FirstCall`, for the n intermediate calls, it is set to `IntermediateCall`, and for the last call it is set to `FinalCall`.

`CallProperty` is used only for `CREATE INDEX`, `DROP INDEX`, `TRUNCATE TABLE`, and for some of the extensible optimizer-related calls for local domain indexes. In all other cases, including DML and query routines for local domain indexes, it is set to `0`.

### ODCIFuncInfo

Object type. Stores functional information.

Table 19-16 ODCIFuncInfo Function Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
    ObjectSchema
    VARCHAR2(30)
| Object schema name
    ObjectName
    VARCHAR2(30)
| Function/package/type name
    MethodName
    VARCHAR2(30)
| Method name for package/type
    Flags
    NUMBER
| Function flags - see `ODCIConst`

### ODCIIndexInfo

Object type. Stores the metadata information related to a domain index. It is passed as a parameter to all `ODCIIndex` routines.

Table 19-17 ODCIIndexInfo Index Related Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
    IndexSchema
    VARCHAR2(30)
| Schema containing domain index
    IndexName
    VARCHAR2(30)
| Name of domain index
    IndexCols
    ODCIColInfoList
| List of indexed columns
    IndexPartition
    VARCHAR2(30)
| For a local domain index, contains the name of the specific index partition
    IndexInfoFlags
    NUMBER
| Possible flags are: `Local` `RangePartn` `Parallel` `Unusable` `IndexOnIOT` `TransTblspc` `FunctionIdx`
    IndexParaDegree
    NUMBER
| The degree of parallelism, if one is specified when creating or rebuilding a domain index or local domain index partition in parallel

### ODCIPredInfo

Object type. Stores the metadata information related to a predicate containing a user-defined operator or function. It is also passed as a parameter to the `ODCIIndexStart`() query routine.

Table 19-18 ODCIPredInfo Operator Related Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
    ObjectSchema
    VARCHAR2(30)
| Schema of operator/function
    ObjectName
    VARCHAR2(30)
| Name of operator/function
    MethodName
    VARCHAR2(30)
| Name of method, applies only to package methods type
    Flags
    NUMBER
| Possible flags are: `PredExactMatch` - Exact Match `PredPrefixMatch` - Prefix Match `PredIncludeStart` - Bounds include the start key value `PredIncludeStop` - Bounds include the stop key value `PredMultiTable` - Predicate involves multiple tables `PredObjectFunc` - Object is a function `PredObjectPlg` - Object is a package `PredObjectType` - Object is a type

### ODCIIndexCtx

Object type. Stores the index context, including the domain index metadata and the rowid. It is passed as parameter to the functional implementation of an operator that expects index context.

Table 19-19 ODCIIndexCtx Index Context Related Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
    IndexInfo
    ODCIIndexInfo
| Stores the metadata information about the domain index
    rid
    VARCHAR2("M_URID_SZ")
| Row identifier of the current row

### ODCIObject

Object type. Stores information about a schema object.

Table 19-20 ODCIObject Index Context Related Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
    ObjectSchema
    VARCHAR2(30)
| Name of schema in which object is located
    ObjectName
    VARCHAR2(30)
| Name of object

### ODCIObjectList

Stores information about a list of schema objects.

Datatype

`VARRAY(32) OF ODCIObject`

### ODCIPartInfo

Object type. Contains the names of both the table partition and the index partition.

Table 19-21 ODCIPartInfo Index-Related Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
TablePartition | `VARCHAR2(30)` | Contains the table partition name
IndexPartition | `VARCHAR2(30)` | Contains the index partition name

### ODCIQueryInfo

Object type. Stores information about the context of a query. It is passed as a parameter to the `ODCIIndexStart` routine.

Table 19-22 ODCIQueryInfo Index Context Related Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
    Flags
    NUMBER
| The following flags can be set: `QueryFirstRows` - Set when the optimizer hint `FIRST_ROWS` is specified in the query `QueryAllRows` - Set when the optimizer hint `ALL_ROWS` is specified in the query
    AncOps
    ODCIObjectList
| Ancillary operators referenced in the query

### ODCIStatsOptions

Object type. Stores options information for `DBMS_STATS`.

Table 19-23 ODCIStatsOptions Cost Information - Attributes

Name | Datatype | Purpose
--- | --- | ---
    Sample
    NUMBER
| Sample size
    Options
    NUMBER
| `DBMS_STATS` options - see "ODCICost"
    Flags
    NUMBER
| `DBMS_STATS` flags - see "ODCICost"

### ODCITabFuncStats

Object type. Stores cardinality information for a table function.

Table 19-24 ODCITabFuncStats Parameter

Parameter | Datatype | Purpose
--- | --- | ---
`num_rows` | `NUMBER` | Contains the number of rows expected to be returned by the table function

### ODCITabStats

Stores table statistics for a table function.

Datatype

`NUMBER`

Table 19-25 ODCITabStats - Attributes

Name | Datatype | Purpose
--- | --- | ---
`Num_rows` | `NUMBER` | Number of rows in table

### ODCIBFileList

Stores varrays of `BFILE`s.

Datatype

`VARRAY(32767) OF BFILE`

### ODCITabFuncInfo

Object type. Stores information on which attributes of user-defined types in a collection need to be set by a table function.

Table 19-26 ODCITabFuncInfo Parameters

Name | Datatype | Purpose
--- | --- | ---
`Attrs` | `ODCINumberList` | Indicates the attributes that need to be set
`RetType` | `AnyType` | For `AnyDataSet` table functions, indicates the actual return type to be expected in the `AnyDataSet` collection

### ODCIDateList

Stores varrays of DATEs.

Datatype

`VARRAY(32767) OF DATE`

### ODCINumberList

Stores varrays of NUMBERs.

Datatype

`VARRAY(32767) OF NUMBER`

### ODCIRawList

Stores varrays of Raws.

Datatype

`VARRAY(32767) OF Raw(2000)`

### ODCIVarchar2List

Stores varrays of VARCHAR2s

Datatype

`VARRAY(32767) OF VARCHAR2(4000)`

### ODCIFuncCallInfo

Object type. Stores information about the functional implementation of an operator.

Table 19-27 ODCIFuncCallInfo - Attributes

Name | Datatype | Purpose
--- | --- | ---
`ColInfo` | `ODCIColInfo` | Information about the column on which the operator is invoked

Usage Notes

A functional implementation can be defined with this parameter only if the operator binding is declared `WITH COLUMN CONTEXT`. This is useful if the functional implementation requires information about the column it was invoked on, and there is no domain index defined on the column. This argument is only populated in the function invocation if the first argument of the operator invocation is a column and there is no domain index defined on that column.

## Mappings of Constants and Types

This section describes language-specific mappings.

### Mappings in PL/SQL

A variety of PL/SQL mappings are common to both Extensible Indexing and the Extensible Optimizer.

- Constants are defined in the `ODCIConst` package found in `catodci.sql`

- Types are defined as object types found in `catodci.sql`

### Mappings in C

Mappings of constants and types are defined for C in the public header file `odci.h`. Each C structure to which a type is mapped has a corresponding indicator structure called `structname_ind` and a reference definition called `structname_ref`.

### Mappings in Java

The ODCI (Oracle Data Cartridge Interface) interfaces are described in the Oracle Data Cartridge Java API Reference documentation. To use these classes, you must first load them.

See Also: Chapter 18, "Cartridge Services Using C, C++ and Java" for loading instructions